home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / mann / scrollbar.n < prev    next >
Text File  |  1994-09-20  |  12KB  |  384 lines
  1. '\"
  2. '\" Copyright (c) 1990 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/wish/man/RCS/scrollbar.n,v 1.10 93/04/01 09:52:54 ouster Exp $ SPRITE (Berkeley)
  22. '/" 
  23. .\" The definitions below are for supplemental macros used in Tcl/Tk
  24. .\" manual entries.
  25. .\"
  26. .\" .HS name section [date [version]]
  27. .\"    Replacement for .TH in other man pages.  See below for valid
  28. .\"    section names.
  29. .\"
  30. .\" .AP type name in/out [indent]
  31. .\"    Start paragraph describing an argument to a library procedure.
  32. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  33. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  34. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  35. .\"    needed;  use .AS below instead)
  36. .\"
  37. .\" .AS [type [name]]
  38. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  39. .\"    name are examples of largest possible arguments that will be passed
  40. .\"    to .AP later.  If args are omitted, default tab stops are used.
  41. .\"
  42. .\" .BS
  43. .\"    Start box enclosure.  From here until next .BE, everything will be
  44. .\"    enclosed in one large box.
  45. .\"
  46. .\" .BE
  47. .\"    End of box enclosure.
  48. .\"
  49. .\" .VS
  50. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  51. .\"    of man pages.
  52. .\"
  53. .\" .VE
  54. .\"    End of vertical sidebar.
  55. .\"
  56. .\" .DS
  57. .\"    Begin an indented unfilled display.
  58. .\"
  59. .\" .DE
  60. .\"    End of indented unfilled display.
  61. .\"
  62. '\"    # Heading for Tcl/Tk man pages
  63. .de HS
  64. .ds ^3 \\0
  65. .if !"\\$3"" .ds ^3 \\$3
  66. .if '\\$2'cmds'       .TH \\$1 1 \\*(^3 \\$4
  67. .if '\\$2'lib'        .TH \\$1 3 \\*(^3 \\$4
  68. .if '\\$2'tcl'        .TH \\$1 n \\*(^3 Tcl "Tcl Built-In Commands"
  69. .if '\\$2'tk'         .TH \\$1 n \\*(^3 Tk "Tk Commands"
  70. .if '\\$2'tclc'        .TH \\$1 3 \\*(^3 Tcl "Tcl Library Procedures"
  71. .if '\\$2'tkc'         .TH \\$1 3 \\*(^3 Tk "Tk Library Procedures"
  72. .if '\\$2'tclcmds'         .TH \\$1 1 \\*(^3 Tk "Tcl Applications"
  73. .if '\\$2'tkcmds'         .TH \\$1 1 \\*(^3 Tk "Tk Applications"
  74. .if t .wh -1.3i ^B
  75. .nr ^l \\n(.l
  76. .ad b
  77. ..
  78. '\"    # Start an argument description
  79. .de AP
  80. .ie !"\\$4"" .TP \\$4
  81. .el \{\
  82. .   ie !"\\$2"" .TP \\n()Cu
  83. .   el          .TP 15
  84. .\}
  85. .ie !"\\$3"" \{\
  86. .ta \\n()Au \\n()Bu
  87. \&\\$1    \\fI\\$2\\fP    (\\$3)
  88. .\".b
  89. .\}
  90. .el \{\
  91. .br
  92. .ie !"\\$2"" \{\
  93. \&\\$1    \\fI\\$2\\fP
  94. .\}
  95. .el \{\
  96. \&\\fI\\$1\\fP
  97. .\}
  98. .\}
  99. ..
  100. '\"    # define tabbing values for .AP
  101. .de AS
  102. .nr )A 10n
  103. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  104. .nr )B \\n()Au+15n
  105. .\"
  106. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  107. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  108. ..
  109. '\"    # BS - start boxed text
  110. '\"    # ^y = starting y location
  111. '\"    # ^b = 1
  112. .de BS
  113. .br
  114. .mk ^y
  115. .nr ^b 1u
  116. .if n .nf
  117. .if n .ti 0
  118. .if n \l'\\n(.lu\(ul'
  119. .if n .fi
  120. ..
  121. '\"    # BE - end boxed text (draw box now)
  122. .de BE
  123. .nf
  124. .ti 0
  125. .mk ^t
  126. .ie n \l'\\n(^lu\(ul'
  127. .el \{\
  128. .\"    Draw four-sided box normally, but don't draw top of
  129. .\"    box if the box started on an earlier page.
  130. .ie !\\n(^b-1 \{\
  131. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  132. .\}
  133. .el \}\
  134. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  135. .\}
  136. .\}
  137. .fi
  138. .br
  139. .nr ^b 0
  140. ..
  141. '\"    # VS - start vertical sidebar
  142. '\"    # ^Y = starting y location
  143. '\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
  144. .de VS
  145. .mk ^Y
  146. .ie n 'mc \s12\(br\s0
  147. .el .nr ^v 1u
  148. ..
  149. '\"    # VE - end of vertical sidebar
  150. .de VE
  151. .ie n 'mc
  152. .el \{\
  153. .ev 2
  154. .nf
  155. .ti 0
  156. .mk ^t
  157. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  158. .sp -1
  159. .fi
  160. .ev
  161. .\}
  162. .nr ^v 0
  163. ..
  164. '\"    # Special macro to handle page bottom:  finish off current
  165. '\"    # box/sidebar if in box/sidebar mode, then invoked standard
  166. '\"    # page bottom macro.
  167. .de ^B
  168. .ev 2
  169. 'ti 0
  170. 'nf
  171. .mk ^t
  172. .if \\n(^b \{\
  173. .\"    Draw three-sided box if this is the box's first page,
  174. .\"    draw two sides but no top otherwise.
  175. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  176. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  177. .\}
  178. .if \\n(^v \{\
  179. .nr ^x \\n(^tu+1v-\\n(^Yu
  180. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  181. .\}
  182. .bp
  183. 'fi
  184. .ev
  185. .if \\n(^b \{\
  186. .mk ^y
  187. .nr ^b 2
  188. .\}
  189. .if \\n(^v \{\
  190. .mk ^Y
  191. .\}
  192. ..
  193. '\"    # DS - begin display
  194. .de DS
  195. .RS
  196. .nf
  197. .sp
  198. ..
  199. '\"    # DE - end display
  200. .de DE
  201. .fi
  202. .RE
  203. .sp .5
  204. ..
  205. .HS scrollbar tk
  206. .BS
  207. '\" Note:  do not modify the .SH NAME line immediately below!
  208. .SH NAME
  209. scrollbar \- Create and manipulate scrollbar widgets
  210. .SH SYNOPSIS
  211. \fBscrollbar\fI pathName \fR?\fIoptions\fR?
  212. .SH "STANDARD OPTIONS"
  213. .LP
  214. .nf
  215. .ta 4c 8c 12c
  216. .VS
  217. \fBactiveForeground\fR    \fBcursor\fR    \fBrelief\fR
  218. .VE
  219. \fBbackground\fR    \fBforeground\fR    \fBrepeatDelay\fR
  220. \fBborderWidth\fR    \fBorient\fR    \fBrepeatInterval\fR
  221. .fi
  222. .LP
  223. See the ``options'' manual entry for details on the standard options.
  224. .SH "WIDGET-SPECIFIC OPTIONS"
  225. .ta 4c
  226. .LP
  227. .nf
  228. Name:    \fBcommand\fR
  229. Class:    \fBCommand\fR
  230. Command-Line Switch:    \fB\-command\fR
  231. .fi
  232. .IP
  233. Specifies the prefix of a Tcl command to invoke to change the view
  234. in the widget associated with the scrollbar.  When a user requests
  235. a view change by manipulating the scrollbar, a Tcl command is
  236. invoked.  The actual command consists of this option followed by
  237. a space and a number.  The number indicates the logical unit that
  238. should appear at the top of the associated window.
  239. .LP
  240. .nf
  241. Name:    \fBwidth\fR
  242. Class:    \fBWidth\fR
  243. Command-Line Switch:    \fB\-width\fR
  244. .fi
  245. .IP
  246. Specifies the desired narrow dimension of the scrollbar window,
  247. not including 3-D border, if any.  For vertical
  248. scrollbars this will be the width and for horizontal scrollbars
  249. this will be the height.
  250. .VS
  251. The value may have any of the forms acceptable to \fBTk_GetPixels\fR.
  252. .VE
  253. .BE
  254.  
  255. .SH DESCRIPTION
  256. .PP
  257. The \fBscrollbar\fR command creates a new window (given by the
  258. \fIpathName\fR argument) and makes it into a scrollbar widget.
  259. Additional
  260. options, described above, may be specified on the command line
  261. or in the option database
  262. to configure aspects of the scrollbar such as its colors, orientation,
  263. and relief.  The \fBscrollbar\fR command returns its
  264. \fIpathName\fR argument.  At the time this command is invoked,
  265. there must not exist a window named \fIpathName\fR, but
  266. \fIpathName\fR's parent must exist.
  267. .PP
  268. A scrollbar is a widget that displays two arrows, one at each end of
  269. the scrollbar, and a \fIslider\fR in the middle portion of the
  270. scrollbar.  A scrollbar is used to provide information about what
  271. is visible in an \fIassociated window\fR that displays an object
  272. of some sort (such as a file being edited or a drawing).
  273. The position and size of the slider indicate which portion of the
  274. object is visible in the associated window.  For example, if the
  275. slider in a vertical scrollbar covers the top third of the area
  276. between the two arrows, it means that the associated window displays
  277. the top third of its object.
  278. .PP
  279. Scrollbars can be used to adjust the view in the associated window
  280. by clicking or dragging with the mouse.  See the BINDINGS section
  281. below for details.
  282.  
  283. .SH "WIDGET COMMAND"
  284. .PP
  285. The \fBscrollbar\fR command creates a new Tcl command whose
  286. name is \fIpathName\fR.  This
  287. command may be used to invoke various
  288. operations on the widget.  It has the following general form:
  289. .DS C
  290. \fIpathName option \fR?\fIarg arg ...\fR?
  291. .DE
  292. \fIOption\fR and the \fIarg\fRs
  293. determine the exact behavior of the command.  The following
  294. commands are possible for scrollbar widgets:
  295. .TP
  296. \fIpathName \fBconfigure\fR ?\fIoption\fR? ?\fIvalue option value ...\fR?
  297. Query or modify the configuration options of the widget.
  298. If no \fIoption\fR is specified, returns a list describing all of
  299. the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for
  300. information on the format of this list).  If \fIoption\fR is specified
  301. with no \fIvalue\fR, then the command returns a list describing the
  302. one named option (this list will be identical to the corresponding
  303. sublist of the value returned if no \fIoption\fR is specified).  If
  304. one or more \fIoption\-value\fR pairs are specified, then the command
  305. modifies the given widget option(s) to have the given value(s);  in
  306. this case the command returns an empty string.
  307. \fIOption\fR may have any of the values accepted by the \fBscrollbar\fR
  308. command.
  309. .TP
  310. \fIpathName \fBget\fR
  311. Returns a Tcl list containing four decimal values, which are
  312. the current \fItotalUnits\fR, \fIwidnowUnits\fR, \fIfirstUnit\fR,
  313. and \fIlastUnit\fR values for the scrollbar.  These are the values
  314. from the most recent \fBset\fR widget command on the scrollbar.
  315. .TP
  316. \fIpathName \fBset\fR \fItotalUnits windowUnits firstUnit lastUnit\fR
  317. This command is invoked to give the scrollbar information about the
  318. widget associated with the scrollbar.  \fITotalUnits\fR is an integer
  319. value giving the total size of the object being displayed in the
  320. associated widget.  The meaning of one unit depends on the associated
  321. widget;  for example, in a text editor widget units might
  322. correspond to lines of
  323. text.  \fIWindowUnits\fR indicates the total number of units that
  324. can fit in the associated window at one time.  \fIFirstUnit\fR
  325. and \fIlastUnit\fR give the indices of the first and last units
  326. currently visible in the associated window (zero corresponds to the
  327. first unit of the object).  This command should
  328. be invoked by the associated widget whenever its object or window
  329. changes size and whenever it changes the view in its window.
  330.  
  331. .SH BINDINGS
  332. .PP
  333. The description below assumes a vertically-oriented scrollbar.
  334. For a horizontally-oriented scrollbar replace the words ``up'', ``down'',
  335. ``top'', and ``bottom'' with ``left'', ``right'', ``left'',
  336. and ``right'', respectively
  337. .PP
  338. A scrollbar widget is divided into five distinct areas.  From top
  339. to bottom, they are:  the top arrow, the top gap (the empty space
  340. between the arrow and the slider), the slider, the bottom gap,
  341. and the bottom arrow.  Pressing mouse button 1 in each area has
  342. a different effect:
  343. .TP 20
  344. \fBtop arrow\fR
  345. Causes the view in the associated window to shift up by one unit
  346. (i.e. the object appears to move down one unit in its window).
  347. If the button is held down the action will auto-repeat.
  348. .TP 20
  349. \fBtop gap\fR
  350. Causes the view in the associated window to shift up by one
  351. less than the number of units in the window
  352. (i.e. the portion of the object that used to appear at the very
  353. top of the window will now appear at the very bottom).
  354. If the button is held down the action will auto-repeat.
  355. .TP 20
  356. \fBslider\fR
  357. Pressing button 1 in this area has no immediate effect except to
  358. cause the slider to appear sunken rather than raised.  However,
  359. if the mouse is moved with the button down then the slider will
  360. be dragged, adjusting the view as the mouse is moved.
  361. .TP 20
  362. \fBbottom gap\fR
  363. Causes the view in the associated window to shift down by one
  364. less than the number of units in the window
  365. (i.e. the portion of the object that used to appear at the very
  366. bottom of the window will now appear at the very top).
  367. If the button is held down the action will auto-repeat.
  368. .TP 20
  369. \fBbottom arrow\fR
  370. Causes the view in the associated window to shift down by one unit
  371. (i.e. the object appears to move up one unit in its window).
  372. If the button is held down the action will auto-repeat.
  373. .PP
  374. Note:  none of the actions described above has an immediate impact
  375. on the position of the slider in the scrollbar.  It simply invokes
  376. the command specified in the \fBcommand\fR option to notify the
  377. associated widget that a change in view is desired.  If the view is
  378. actually changed then the associated widget must invoke the
  379. scrollbar's \fBset\fR widget command to change what is displayed in
  380. the scrollbar.
  381.  
  382. .SH KEYWORDS
  383. scrollbar, widget
  384.